﻿<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="../assets/css/yui-cssgrids-min.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <link rel="stylesheet" href="../assets/css/main.css" id="site_styles">
    <link rel="shortcut icon" type="image/x-icon" href="../assets/favicon.ico">
    <script src="../assets/js/yui-source.js"></script>
	<title>EaselJS v1.0.0 API Documentation : easeljs/display/Bitmap.js</title>
</head>
<body class="yui3-skin-sam">

<div id="doc">
    <div id="hd" class="yui3-g header">
        <div class="yui3-u-3-4">
            
                <h1><a href="http://createjs.site/easeljs"><img src="../assets/docs-icon-EaselJS.png" title="EaselJS"></a></h1>
            
        </div>
        <div class="version">
            <em>API Documentation for: 1.0.0</em>
        </div>
    </div>
    <div id="bd" class="yui3-g">

        <div class="yui3-u-1-4">
            <div id="docs-sidebar" class="sidebar apidocs">
                <div id="api-list">
    <h2 class="off-left">APIs</h2>
    <div id="api-tabview" class="tabview">
        <ul class="tabs">
            <li><a href="#api-classes">Classes</a></li>
        </ul>

        <div id="api-tabview-filter">
            <input type="search" id="api-filter" placeholder="Type to filter APIs">
        </div>

        <div id="api-tabview-panel">
            <ul id="api-classes" class="apis classes">
            
                <li><a href="../classes/AlphaMapFilter.html">AlphaMapFilter</a></li>
            
                <li><a href="../classes/AlphaMaskFilter.html">AlphaMaskFilter</a></li>
            
                <li><a href="../classes/Bitmap.html">Bitmap</a></li>
            
                <li><a href="../classes/BitmapCache.html">BitmapCache</a></li>
            
                <li><a href="../classes/BitmapText.html">BitmapText</a></li>
            
                <li><a href="../classes/BlurFilter.html">BlurFilter</a></li>
            
                <li><a href="../classes/ButtonHelper.html">ButtonHelper</a></li>
            
                <li><a href="../classes/ColorFilter.html">ColorFilter</a></li>
            
                <li><a href="../classes/ColorMatrix.html">ColorMatrix</a></li>
            
                <li><a href="../classes/ColorMatrixFilter.html">ColorMatrixFilter</a></li>
            
                <li><a href="../classes/Container.html">Container</a></li>
            
                <li><a href="../classes/DisplayObject.html">DisplayObject</a></li>
            
                <li><a href="../classes/DisplayProps.html">DisplayProps</a></li>
            
                <li><a href="../classes/DOMElement.html">DOMElement</a></li>
            
                <li><a href="../classes/EaselJS.html">EaselJS</a></li>
            
                <li><a href="../classes/Event.html">Event</a></li>
            
                <li><a href="../classes/EventDispatcher.html">EventDispatcher</a></li>
            
                <li><a href="../classes/Filter.html">Filter</a></li>
            
                <li><a href="../classes/Graphics.html">Graphics</a></li>
            
                <li><a href="../classes/Graphics.Arc.html">Graphics.Arc</a></li>
            
                <li><a href="../classes/Graphics.ArcTo.html">Graphics.ArcTo</a></li>
            
                <li><a href="../classes/Graphics.BeginPath.html">Graphics.BeginPath</a></li>
            
                <li><a href="../classes/Graphics.BezierCurveTo.html">Graphics.BezierCurveTo</a></li>
            
                <li><a href="../classes/Graphics.Circle.html">Graphics.Circle</a></li>
            
                <li><a href="../classes/Graphics.ClosePath.html">Graphics.ClosePath</a></li>
            
                <li><a href="../classes/Graphics.Ellipse.html">Graphics.Ellipse</a></li>
            
                <li><a href="../classes/Graphics.Fill.html">Graphics.Fill</a></li>
            
                <li><a href="../classes/Graphics.LineTo.html">Graphics.LineTo</a></li>
            
                <li><a href="../classes/Graphics.MoveTo.html">Graphics.MoveTo</a></li>
            
                <li><a href="../classes/Graphics.PolyStar.html">Graphics.PolyStar</a></li>
            
                <li><a href="../classes/Graphics.QuadraticCurveTo.html">Graphics.QuadraticCurveTo</a></li>
            
                <li><a href="../classes/Graphics.Rect.html">Graphics.Rect</a></li>
            
                <li><a href="../classes/Graphics.RoundRect.html">Graphics.RoundRect</a></li>
            
                <li><a href="../classes/Graphics.Stroke.html">Graphics.Stroke</a></li>
            
                <li><a href="../classes/Graphics.StrokeDash.html">Graphics.StrokeDash</a></li>
            
                <li><a href="../classes/Graphics.StrokeStyle.html">Graphics.StrokeStyle</a></li>
            
                <li><a href="../classes/Matrix2D.html">Matrix2D</a></li>
            
                <li><a href="../classes/MouseEvent.html">MouseEvent</a></li>
            
                <li><a href="../classes/MovieClip.html">MovieClip</a></li>
            
                <li><a href="../classes/MovieClipPlugin.html">MovieClipPlugin</a></li>
            
                <li><a href="../classes/Point.html">Point</a></li>
            
                <li><a href="../classes/Rectangle.html">Rectangle</a></li>
            
                <li><a href="../classes/Shadow.html">Shadow</a></li>
            
                <li><a href="../classes/Shape.html">Shape</a></li>
            
                <li><a href="../classes/Sprite.html">Sprite</a></li>
            
                <li><a href="../classes/SpriteSheet.html">SpriteSheet</a></li>
            
                <li><a href="../classes/SpriteSheetBuilder.html">SpriteSheetBuilder</a></li>
            
                <li><a href="../classes/SpriteSheetUtils.html">SpriteSheetUtils</a></li>
            
                <li><a href="../classes/Stage.html">Stage</a></li>
            
                <li><a href="../classes/StageGL.html">StageGL</a></li>
            
                <li><a href="../classes/Text.html">Text</a></li>
            
                <li><a href="../classes/Ticker.html">Ticker</a></li>
            
                <li><a href="../classes/Touch.html">Touch</a></li>
            
                <li><a href="../classes/UID.html">UID</a></li>
            
                <li><a href="../classes/Utility Methods.html">Utility Methods</a></li>
            
                <li><a href="../classes/VideoBuffer.html">VideoBuffer</a></li>
            
                <li><a href="../classes/WebGLInspector.html">WebGLInspector</a></li>
            
            </ul>

            <ul id="api-modules" class="apis modules">
            
                <li><a href="../modules/CreateJS.html">CreateJS</a></li>
            
                <li><a href="../modules/EaselJS.html">EaselJS</a></li>
            
            </ul>
        </div>
    </div>
</div>

            </div>
        </div>
        <div class="yui3-u-3-4">
            <div id="api-options">
        Show:
        <label for="api-show-inherited">
            <input type="checkbox" id="api-show-inherited" checked="">
            Inherited
        </label>

        <label for="api-show-protected">
            <input type="checkbox" id="api-show-protected">
            Protected
        </label>

        <label for="api-show-private">
            <input type="checkbox" id="api-show-private">
            Private
        </label>
        <label for="api-show-deprecated">
            <input type="checkbox" id="api-show-deprecated">
            Deprecated
        </label>

    </div>
            <div class="apidocs">
                <div id="docs-main">
                    <div class="content source-content">
                        <script>
	var name = easeljs/display/Bitmap.js      
</script>
<h1 class="file-heading">File:Bitmap.js</h1>

<div class="file">
    <pre class="code prettyprint linenums">
/*
* Bitmap
* Visit http://createjs.site/ for documentation, updates and examples.
*
* Copyright (c) 2010 gskinner.com, inc.
* 
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the &quot;Software&quot;), to deal in the Software without
* restriction, including without limitation the rights to use,
* copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following
* conditions:
* 
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
* 
* THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*/

/**
* @module EaselJS
*/

// namespace:
this.createjs = this.createjs||{};

(function() {
	
	/**
	 * A Bitmap represents an Image, Canvas, or Video in the display list. A Bitmap can be instantiated using an existing
	 * HTML element, or a string.
	 *
	 * &lt;h4&gt;Example&lt;/h4&gt;
	 *
	 * 	var bitmap = new createjs.Bitmap(&quot;imagePath.jpg&quot;);
	 *
	 * &lt;strong&gt;Notes:&lt;/strong&gt;
	 * &lt;ol&gt;
	 * 	&lt;li&gt;When using a video source that may loop or seek, use a {{#crossLink &quot;VideoBuffer&quot;}}{{/crossLink}} object to
	 * 	 prevent blinking / flashing.
	 * 	&lt;li&gt;When a string path or image tag that is not yet loaded is used, the stage may need to be redrawn before it
	 * 	 will be displayed.&lt;/li&gt;
	 * 	&lt;li&gt;Bitmaps with an SVG source currently will not respect an alpha value other than 0 or 1. To get around this,
	 * 	the Bitmap can be cached.&lt;/li&gt;
	 * 	&lt;li&gt;Bitmaps with an SVG source will taint the canvas with cross-origin data, which prevents interactivity. This
	 * 	happens in all browsers except recent Firefox builds.&lt;/li&gt;
	 * 	&lt;li&gt;Images loaded cross-origin will throw cross-origin security errors when interacted with using a mouse, using
	 * 	methods such as &#x60;getObjectUnderPoint&#x60;, or using filters, or caching. You can get around this by setting
	 * 	&#x60;crossOrigin&#x60; flags on your images before passing them to EaselJS, eg: &#x60;img.crossOrigin=&quot;Anonymous&quot;;&#x60;&lt;/li&gt;
	 * &lt;/ol&gt;
	 *
	 * @class Bitmap
	 * @extends DisplayObject
	 * @constructor
	 * @param {CanvasImageSource | String | Object} imageOrUri The source image to display. This can be a CanvasImageSource
	 * (image, video, canvas), an object with a &#x60;getImage&#x60; method that returns a CanvasImageSource, or a string URL to an image.
	 * If the latter, a new Image instance with the URL as its src will be used.
	 **/
	function Bitmap(imageOrUri) {
		this.DisplayObject_constructor();
		
		
	// public properties:
		/**
		 * The source image to display. This can be a CanvasImageSource
		 * (image, video, canvas), an object with a &#x60;getImage&#x60; method that returns a CanvasImageSource, or a string URL to an image.
		 * If the latter, a new Image instance with the URL as its src will be used.
		 * @property image
		 * @type CanvasImageSource | Object
		 **/
		if (typeof imageOrUri == &quot;string&quot;) {
			this.image = document.createElement(&quot;img&quot;);
			this.image.src = imageOrUri;
		} else {
			this.image = imageOrUri;
		}
	
		/**
		 * Specifies an area of the source image to draw. If omitted, the whole image will be drawn.
		 * Notes:
		 * &lt;ul&gt;
		 *     &lt;li&gt;that video sources must have a width / height set to work correctly with &#x60;sourceRect&#x60;&lt;/li&gt;
		 *     &lt;li&gt;Cached objects will ignore the &#x60;sourceRect&#x60; property&lt;/li&gt;
		 * &lt;/ul&gt;
		 * @property sourceRect
		 * @type Rectangle
		 * @default null
		 */
		this.sourceRect = null;

	// private properties:
		// Docced in superclass
		this._webGLRenderStyle = createjs.DisplayObject._StageGL_BITMAP;
	}
	var p = createjs.extend(Bitmap, createjs.DisplayObject);
	
	
// public methods:
	/**
	 * Constructor alias for backwards compatibility. This method will be removed in future versions.
	 * Subclasses should be updated to use {{#crossLink &quot;Utility Methods/extends&quot;}}{{/crossLink}}.
	 * @method initialize
	 * @deprecated in favour of &#x60;createjs.promote()&#x60;
	 **/
	p.initialize = Bitmap; // TODO: deprecated.

	/**
	 * Returns true or false indicating whether the display object would be visible if drawn to a canvas.
	 * This does not account for whether it would be visible within the boundaries of the stage.
	 *
	 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
	 * @method isVisible
	 * @return {Boolean} Boolean indicating whether the display object would be visible if drawn to a canvas
	 **/
	p.isVisible = function() {
		var image = this.image;
		var hasContent = this.cacheCanvas || (image &amp;&amp; (image.naturalWidth || image.getContext || image.readyState &gt;= 2));
		return !!(this.visible &amp;&amp; this.alpha &gt; 0 &amp;&amp; this.scaleX != 0 &amp;&amp; this.scaleY != 0 &amp;&amp; hasContent);
	};

	/**
	 * Draws the display object into the specified context ignoring its visible, alpha, shadow, and transform.
	 * Returns true if the draw was handled (useful for overriding functionality).
	 *
	 * NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
	 * @method draw
	 * @param {CanvasRenderingContext2D} ctx The canvas 2D context object to draw into.
	 * @param {Boolean} [ignoreCache=false] Indicates whether the draw operation should ignore any current cache.
	 * For example, used for drawing the cache (to prevent it from simply drawing an existing cache back
	 * into itself).
	 * @return {Boolean}
	 **/
	p.draw = function(ctx, ignoreCache) {
		if (this.DisplayObject_draw(ctx, ignoreCache)) { return true; }
		var img = this.image, rect = this.sourceRect;
		if (img.getImage) { img = img.getImage(); }
		if (!img) { return true; }
		if (rect) {
			// some browsers choke on out of bound values, so we&#x27;ll fix them:
			var x1 = rect.x, y1 = rect.y, x2 = x1 + rect.width, y2 = y1 + rect.height, x = 0, y = 0, w = img.width, h = img.height;
			if (x1 &lt; 0) { x -= x1; x1 = 0; }
			if (x2 &gt; w) { x2 = w; }
			if (y1 &lt; 0) { y -= y1; y1 = 0; }
			if (y2 &gt; h) { y2 = h; }
			ctx.drawImage(img, x1, y1, x2-x1, y2-y1, x, y, x2-x1, y2-y1);
		} else {
			ctx.drawImage(img, 0, 0);
		}
		return true;
	};
	
	//Note, the doc sections below document using the specified APIs (from DisplayObject)  from
	//Bitmap. This is why they have no method implementations.
	
	/**
	 * Because the content of a Bitmap is already in a simple format, cache is unnecessary for Bitmap instances.
	 * You should &lt;b&gt;not&lt;/b&gt; cache Bitmap instances as it can degrade performance.
	 *
	 * &lt;strong&gt;However: If you want to use a filter on a Bitmap, you &lt;em&gt;MUST&lt;/em&gt; cache it, or it will not work.&lt;/strong&gt;
	 * To see the API for caching, please visit the DisplayObject {{#crossLink &quot;DisplayObject/cache&quot;}}{{/crossLink}}
	 * method.
	 * @method cache
	 **/
	
	/**
	 * Because the content of a Bitmap is already in a simple format, cache is unnecessary for Bitmap instances.
	 * You should &lt;b&gt;not&lt;/b&gt; cache Bitmap instances as it can degrade performance.
	 *
	 * &lt;strong&gt;However: If you want to use a filter on a Bitmap, you &lt;em&gt;MUST&lt;/em&gt; cache it, or it will not work.&lt;/strong&gt;
	 * To see the API for caching, please visit the DisplayObject {{#crossLink &quot;DisplayObject/cache&quot;}}{{/crossLink}}
	 * method.
	 * @method updateCache
	 **/
	
	/**
	 * Because the content of a Bitmap is already in a simple format, cache is unnecessary for Bitmap instances.
	 * You should &lt;b&gt;not&lt;/b&gt; cache Bitmap instances as it can degrade performance.
	 *
	 * &lt;strong&gt;However: If you want to use a filter on a Bitmap, you &lt;em&gt;MUST&lt;/em&gt; cache it, or it will not work.&lt;/strong&gt;
	 * To see the API for caching, please visit the DisplayObject {{#crossLink &quot;DisplayObject/cache&quot;}}{{/crossLink}}
	 * method.
	 * @method uncache
	 **/

	// Docced in superclass
	p.getBounds = function() {
		var rect = this.DisplayObject_getBounds();
		if (rect) { return rect; }
		var image = this.image, o = this.sourceRect || image;
		var hasContent = (image &amp;&amp; (image.naturalWidth || image.getContext || image.readyState &gt;= 2));
		return hasContent ? this._rectangle.setValues(0, 0, o.width, o.height) : null;
	};
	
	/**
	 * Returns a clone of the Bitmap instance.
	 * @method clone
	 * @param {Boolean} node Whether the underlying dom element should be cloned as well.
	 * @return {Bitmap} a clone of the Bitmap instance.
	 **/
	p.clone = function(node) {
		var image = this.image;
		if(image &amp;&amp; node){ image = image.cloneNode(); }
		var o = new Bitmap(image);
		if (this.sourceRect) { o.sourceRect = this.sourceRect.clone(); }
		this._cloneProps(o);
		return o;
	};
	
	/**
	 * Returns a string representation of this object.
	 * @method toString
	 * @return {String} a string representation of the instance.
	 **/
	p.toString = function() {
		return &quot;[Bitmap (name=&quot;+  this.name +&quot;)]&quot;;
	};

	
	createjs.Bitmap = createjs.promote(Bitmap, &quot;DisplayObject&quot;);
}());

    </pre>
</div>

                    </div>
                </div>
            </div>
        </div>
    </div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script src="../assets/js/yui-prettify.js"></script>
<script src="../api.js"></script>
<script src="../assets/js/api-filter.js"></script>
<script src="../assets/js/api-list.js"></script>
<script src="../assets/js/api-search.js"></script>
<script src="../assets/js/apidocs.js"></script>
</body>
</html>
